


<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
  "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">


<html xmlns="http://www.w3.org/1999/xhtml">
  <head>
    <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
    
    <title>Actors (Java) &mdash; Akka Documentation</title>
    
    <link rel="stylesheet" href="../_static/style.css" type="text/css" />
    <link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
    <link rel="stylesheet" href="../_static/prettify.css" type="text/css" />
    <link rel="stylesheet" href="../_static/base.css" type="text/css" />
    <link rel="stylesheet" href="../_static/docs.css" type="text/css" />
    <link rel="stylesheet" href="http://fonts.googleapis.com/css?family=Exo:300,400,600,700" type="text/css" />
    
    <script type="text/javascript">
      var DOCUMENTATION_OPTIONS = {
        URL_ROOT:    '../',
        VERSION:     '2.0.1',
        COLLAPSE_INDEX: false,
        FILE_SUFFIX: '.html',
        HAS_SOURCE:  true
      };
    </script>
    <script type="text/javascript" src="../_static/jquery.js"></script>
    <script type="text/javascript" src="../_static/underscore.js"></script>
    <script type="text/javascript" src="../_static/doctools.js"></script>
    <script type="text/javascript" src="../_static/toc.js"></script>
    <script type="text/javascript" src="../_static/prettify.js"></script>
    <script type="text/javascript" src="../_static/highlightCode.js"></script>
    <script type="text/javascript" src="../_static/effects.core.js"></script>
    <script type="text/javascript" src="../_static/effects.highlight.js"></script>
    <script type="text/javascript" src="../_static/scrollTo.js"></script>
    <script type="text/javascript" src="../_static/contentsFix.js"></script>
    <link rel="shortcut icon" href="../_static/favicon.ico"/>
    <link rel="top" title="Akka Documentation" href="../index.html" />
    <link rel="up" title="Java API" href="index.html" />
    <link rel="next" title="Typed Actors (Java)" href="typed-actors.html" />
    <link rel="prev" title="Java API" href="index.html" /> 
  </head>
  <body>
  <div class="navbar">
    <div class="navbar-inner">
      <div class="container">
        <div class="navbar-logo">
          <a href="http://akka.io"><img src="../_static/logo-small.png" /></a>
        </div>    
        <ul class="nav">
          <li><a href="http://akka.io/docs">Documentation</a></li>
          <li><a href="http://akka.io/downloads">Download</a></li>
          <li><a href="http://groups.google.com/group/akka-user">Mailing List</a></li>
          <li><a href="http://github.com/akka/akka">Code</a></li>           
          <li><a href="http://typesafe.com/products/typesafe-subscription">Commerical Support</a></li>
        </ul>
      </div>
    </div>
  </div>
  <div class="main">
    <div class="container">
      <div class="page-title">Actors (Java)</div><div class="pdf-link"><a href="http://akka.io/docs/akka/2.0.1/Akka.pdf"><img src="../_static/pdf-icon.png" style="height: 40px;" /></a></div></div>
    <div class="main-container">
      <div class="container">
        <div class="row">
          <div class="span12">
            <ul class="breadcrumb">           
              <li>
                 <span class="divider">|</span> <a href="typed-actors.html">Typed Actors (Java)</a> <span class="divider">»</span>
              </li>
              <li>
                <a href="../index.html">Contents</a>
              </li>
              <li>
                <span class="divider">«</span> <a href="index.html">Java API</a> <span class="divider">|</span>
              </li>
              <li>
                Version 2.0.1
              </li>
            </ul>         
          </div>
        </div>
        <div class="row">
          <div class="span9">
            
  <div class="section" id="actors-java">
<span id="untyped-actors-java"></span><h1>Actors (Java)</h1>
<p>The <a class="reference external" href="http://en.wikipedia.org/wiki/Actor_model">Actor Model</a> provides a higher level of abstraction for writing concurrent
and distributed systems. It alleviates the developer from having to deal with
explicit locking and thread management, making it easier to write correct
concurrent and parallel systems. Actors were defined in the 1973 paper by Carl
Hewitt but have been popularized by the Erlang language, and used for example at
Ericsson with great success to build highly concurrent and reliable telecom
systems.</p>
<p>The API of Akka’s Actors is similar to Scala Actors which has borrowed some of
its syntax from Erlang.</p>
<div class="section" id="creating-actors">
<h2>Creating Actors</h2>
<p>Since Akka enforces parental supervision every actor is supervised and
(potentially) the supervisor of its children; it is advisable that you
familiarize yourself with <a class="reference internal" href="../general/actor-systems.html#actor-systems"><em>Actor Systems</em></a> and <a class="reference internal" href="../general/supervision.html#supervision"><em>Supervision and Monitoring</em></a> and it
may also help to read <a class="reference internal" href="../general/addressing.html#actorof-vs-actorfor"><em>Summary: actorOf vs. actorFor</em></a>.</p>
<div class="section" id="defining-an-actor-class">
<h3>Defining an Actor class</h3>
<p>Actor in Java are implemented by extending the <tt class="docutils literal"><span class="pre">UntypedActor</span></tt> class and implementing the
<tt class="xref py py-meth docutils literal"><span class="pre">onReceive</span></tt> method. This method takes the message as a parameter.</p>
<p>Here is an example:</p>
<div class="highlight-scala"><div class="highlight"><pre><span class="k">import</span> <span class="nn">akka.actor.UntypedActor</span><span class="o">;</span>
<span class="k">import</span> <span class="nn">akka.event.Logging</span><span class="o">;</span>
<span class="k">import</span> <span class="nn">akka.event.LoggingAdapter</span><span class="o">;</span>

<span class="n">public</span> <span class="k">class</span> <span class="nc">MyUntypedActor</span> <span class="k">extends</span> <span class="nc">UntypedActor</span> <span class="o">{</span>
  <span class="nc">LoggingAdapter</span> <span class="n">log</span> <span class="k">=</span> <span class="nc">Logging</span><span class="o">.</span><span class="n">getLogger</span><span class="o">(</span><span class="n">getContext</span><span class="o">().</span><span class="n">system</span><span class="o">(),</span> <span class="k">this</span><span class="o">);</span>

  <span class="n">public</span> <span class="n">void</span> <span class="n">onReceive</span><span class="o">(</span><span class="nc">Object</span> <span class="n">message</span><span class="o">)</span> <span class="n">throws</span> <span class="nc">Exception</span> <span class="o">{</span>
    <span class="k">if</span> <span class="o">(</span><span class="n">message</span> <span class="n">instanceof</span> <span class="nc">String</span><span class="o">)</span>
      <span class="n">log</span><span class="o">.</span><span class="n">info</span><span class="o">(</span><span class="s">&quot;Received String message: {}&quot;</span><span class="o">,</span> <span class="n">message</span><span class="o">);</span>
    <span class="k">else</span>
      <span class="n">unhandled</span><span class="o">(</span><span class="n">message</span><span class="o">);</span>
  <span class="o">}</span>
<span class="o">}</span>
</pre></div>
</div>
</div>
<div class="section" id="props">
<h3>Props</h3>
<p><tt class="docutils literal"><span class="pre">Props</span></tt> is a configuration class to specify options for the creation
of actors. Here are some examples on how to create a <tt class="docutils literal"><span class="pre">Props</span></tt> instance.</p>
<div class="highlight-scala"><div class="highlight"><pre><span class="nc">Props</span> <span class="n">props1</span> <span class="k">=</span> <span class="k">new</span> <span class="nc">Props</span><span class="o">();</span>
<span class="nc">Props</span> <span class="n">props2</span> <span class="k">=</span> <span class="k">new</span> <span class="nc">Props</span><span class="o">(</span><span class="nc">MyUntypedActor</span><span class="o">.</span><span class="n">class</span><span class="o">);</span>
<span class="nc">Props</span> <span class="n">props3</span> <span class="k">=</span> <span class="k">new</span> <span class="nc">Props</span><span class="o">(</span><span class="k">new</span> <span class="nc">UntypedActorFactory</span><span class="o">()</span> <span class="o">{</span>
  <span class="n">public</span> <span class="nc">UntypedActor</span> <span class="n">create</span><span class="o">()</span> <span class="o">{</span>
    <span class="k">return</span> <span class="k">new</span> <span class="nc">MyUntypedActor</span><span class="o">();</span>
  <span class="o">}</span>
<span class="o">});</span>
<span class="nc">Props</span> <span class="n">props4</span> <span class="k">=</span> <span class="n">props1</span><span class="o">.</span><span class="n">withCreator</span><span class="o">(</span><span class="k">new</span> <span class="nc">UntypedActorFactory</span><span class="o">()</span> <span class="o">{</span>
  <span class="n">public</span> <span class="nc">UntypedActor</span> <span class="n">create</span><span class="o">()</span> <span class="o">{</span>
    <span class="k">return</span> <span class="k">new</span> <span class="nc">MyUntypedActor</span><span class="o">();</span>
  <span class="o">}</span>
<span class="o">});</span>
</pre></div>
</div>
</div>
<div class="section" id="creating-actors-with-props">
<h3>Creating Actors with Props</h3>
<p>Actors are created by passing in a <tt class="docutils literal"><span class="pre">Props</span></tt> instance into the <tt class="docutils literal"><span class="pre">actorOf</span></tt> factory method.</p>
<div class="highlight-scala"><div class="highlight"><pre><span class="nc">ActorRef</span> <span class="n">myActor</span> <span class="k">=</span> <span class="n">system</span><span class="o">.</span><span class="n">actorOf</span><span class="o">(</span><span class="k">new</span> <span class="nc">Props</span><span class="o">(</span><span class="nc">MyUntypedActor</span><span class="o">.</span><span class="n">class</span><span class="o">).</span><span class="n">withDispatcher</span><span class="o">(</span><span class="s">&quot;my-dispatcher&quot;</span><span class="o">),</span> <span class="s">&quot;myactor&quot;</span><span class="o">);</span>
</pre></div>
</div>
</div>
<div class="section" id="creating-actors-with-default-constructor">
<h3>Creating Actors with default constructor</h3>
<div class="highlight-scala"><div class="highlight"><pre><span class="k">import</span> <span class="nn">akka.actor.ActorRef</span><span class="o">;</span>
<span class="k">import</span> <span class="nn">akka.actor.ActorSystem</span><span class="o">;</span>
<span class="k">import</span> <span class="nn">akka.actor.Props</span><span class="o">;</span>
    <span class="nc">ActorSystem</span> <span class="n">system</span> <span class="k">=</span> <span class="nc">ActorSystem</span><span class="o">.</span><span class="n">create</span><span class="o">(</span><span class="s">&quot;MySystem&quot;</span><span class="o">);</span>
    <span class="nc">ActorRef</span> <span class="n">myActor</span> <span class="k">=</span> <span class="n">system</span><span class="o">.</span><span class="n">actorOf</span><span class="o">(</span><span class="k">new</span> <span class="nc">Props</span><span class="o">(</span><span class="nc">MyUntypedActor</span><span class="o">.</span><span class="n">class</span><span class="o">),</span> <span class="s">&quot;myactor&quot;</span><span class="o">);</span>
</pre></div>
</div>
<p>The call to <tt class="xref py py-meth docutils literal"><span class="pre">actorOf</span></tt> returns an instance of <tt class="docutils literal"><span class="pre">ActorRef</span></tt>. This is a handle to
the <tt class="docutils literal"><span class="pre">UntypedActor</span></tt> instance which you can use to interact with the <tt class="docutils literal"><span class="pre">UntypedActor</span></tt>. The
<tt class="docutils literal"><span class="pre">ActorRef</span></tt> is immutable and has a one to one relationship with the Actor it
represents. The <tt class="docutils literal"><span class="pre">ActorRef</span></tt> is also serializable and network-aware. This means
that you can serialize it, send it over the wire and use it on a remote host and
it will still be representing the same Actor on the original node, across the
network.</p>
<p>In the above example the actor was created from the system. It is also possible
to create actors from other actors with the actor <tt class="docutils literal"><span class="pre">context</span></tt>. The difference is
how the supervisor hierarchy is arranged. When using the context the current actor
will be supervisor of the created child actor. When using the system it will be
a top level actor, that is supervised by the system (internal guardian actor).</p>
<div class="highlight-scala"><div class="highlight"><pre><span class="n">public</span> <span class="k">class</span> <span class="nc">FirstUntypedActor</span> <span class="k">extends</span> <span class="nc">UntypedActor</span> <span class="o">{</span>
  <span class="nc">ActorRef</span> <span class="n">myActor</span> <span class="k">=</span> <span class="n">getContext</span><span class="o">().</span><span class="n">actorOf</span><span class="o">(</span><span class="k">new</span> <span class="nc">Props</span><span class="o">(</span><span class="nc">MyActor</span><span class="o">.</span><span class="n">class</span><span class="o">),</span> <span class="s">&quot;myactor&quot;</span><span class="o">);</span>
</pre></div>
</div>
<p>The name parameter is optional, but you should preferably name your actors, since
that is used in log messages and for identifying actors. The name must not be empty
or start with <tt class="docutils literal"><span class="pre">$</span></tt>. If the given name is already in use by another child to the
same parent actor an <cite>InvalidActorNameException</cite> is thrown.</p>
<p>Actors are automatically started asynchronously when created.
When you create the <tt class="docutils literal"><span class="pre">UntypedActor</span></tt> then it will automatically call the <tt class="docutils literal"><span class="pre">preStart</span></tt>
callback method on the <tt class="docutils literal"><span class="pre">UntypedActor</span></tt> class. This is an excellent place to
add initialization code for the actor.</p>
<div class="highlight-java"><div class="highlight"><pre><span class="nd">@Override</span>
<span class="kd">public</span> <span class="kt">void</span> <span class="nf">preStart</span><span class="o">()</span> <span class="o">{</span>
  <span class="o">...</span> <span class="c1">// initialization code</span>
<span class="o">}</span>
</pre></div>
</div>
</div>
<div class="section" id="creating-actors-with-non-default-constructor">
<h3>Creating Actors with non-default constructor</h3>
<p>If your UntypedActor has a constructor that takes parameters then you can&#8217;t create it using
&#8216;actorOf(new Props(clazz))&#8217;. Then you can instead pass in &#8216;new Props(new UntypedActorFactory() {..})&#8217;
in which you can create the Actor in any way you like.</p>
<p>Here is an example:</p>
<div class="highlight-scala"><div class="highlight"><pre><span class="c1">// allows passing in arguments to the MyActor constructor</span>
<span class="nc">ActorRef</span> <span class="n">myActor</span> <span class="k">=</span> <span class="n">system</span><span class="o">.</span><span class="n">actorOf</span><span class="o">(</span><span class="k">new</span> <span class="nc">Props</span><span class="o">(</span><span class="k">new</span> <span class="nc">UntypedActorFactory</span><span class="o">()</span> <span class="o">{</span>
  <span class="n">public</span> <span class="nc">UntypedActor</span> <span class="n">create</span><span class="o">()</span> <span class="o">{</span>
    <span class="k">return</span> <span class="k">new</span> <span class="nc">MyActor</span><span class="o">(</span><span class="s">&quot;...&quot;</span><span class="o">);</span>
  <span class="o">}</span>
<span class="o">}),</span> <span class="s">&quot;myactor&quot;</span><span class="o">);</span>
</pre></div>
</div>
<p>This way of creating the Actor is also great for integrating with Dependency Injection
(DI) frameworks like Guice or Spring.</p>
</div>
</div>
<div class="section" id="untypedactor-api">
<h2>UntypedActor API</h2>
<p>The <tt class="xref py py-class docutils literal"><span class="pre">UntypedActor</span></tt> class defines only one abstract method, the above mentioned
<tt class="xref py py-meth docutils literal"><span class="pre">onReceive(Object</span> <span class="pre">message)</span></tt>, which implements the behavior of the actor.</p>
<p>If the current actor behavior does not match a received message,
<tt class="xref py py-meth docutils literal"><span class="pre">unhandled</span></tt> is called, which by default publishes a <tt class="docutils literal"><span class="pre">new</span>
<span class="pre">akka.actor.UnhandledMessage(message,</span> <span class="pre">sender,</span> <span class="pre">recipient)</span></tt> on the actor system’s
event stream.</p>
<p>In addition, it offers:</p>
<ul class="simple">
<li><tt class="xref py py-obj docutils literal"><span class="pre">getSelf()</span></tt> reference to the <tt class="xref py py-class docutils literal"><span class="pre">ActorRef</span></tt> of the actor</li>
<li><tt class="xref py py-obj docutils literal"><span class="pre">getSender()</span></tt> reference sender Actor of the last received message, typically used as described in <a class="reference internal" href="#untypedactor-reply"><em>Reply to messages</em></a></li>
<li><tt class="xref py py-obj docutils literal"><span class="pre">supervisorStrategy()</span></tt> user overridable definition the strategy to use for supervising child actors</li>
<li><tt class="xref py py-obj docutils literal"><span class="pre">getContext()</span></tt> exposes contextual information for the actor and the current message, such as:<ul>
<li>factory methods to create child actors (<tt class="xref py py-meth docutils literal"><span class="pre">actorOf</span></tt>)</li>
<li>system that the actor belongs to</li>
<li>parent supervisor</li>
<li>supervised children</li>
<li>lifecycle monitoring</li>
<li>hotswap behavior stack as described in <a class="reference internal" href="#untypedactor-hotswap"><em>HotSwap</em></a></li>
</ul>
</li>
</ul>
<p>The remaining visible methods are user-overridable life-cycle hooks which are
described in the following:</p>
<div class="highlight-scala"><div class="highlight"><pre><span class="n">public</span> <span class="n">void</span> <span class="n">preStart</span><span class="o">()</span> <span class="o">{</span>
<span class="o">}</span>

<span class="n">public</span> <span class="n">void</span> <span class="n">preRestart</span><span class="o">(</span><span class="nc">Throwable</span> <span class="n">reason</span><span class="o">,</span> <span class="nc">Option</span><span class="o">&lt;</span><span class="nc">Object</span><span class="o">&gt;</span> <span class="n">message</span><span class="o">)</span> <span class="o">{</span>
  <span class="k">for</span> <span class="o">(</span><span class="nc">ActorRef</span> <span class="n">each</span> <span class="k">:</span> <span class="kt">getContext</span><span class="o">()</span><span class="kt">.getChildren</span><span class="o">())</span>
    <span class="n">getContext</span><span class="o">().</span><span class="n">stop</span><span class="o">(</span><span class="n">each</span><span class="o">);</span>
  <span class="n">postStop</span><span class="o">();</span>
<span class="o">}</span>

<span class="n">public</span> <span class="n">void</span> <span class="n">postRestart</span><span class="o">(</span><span class="nc">Throwable</span> <span class="n">reason</span><span class="o">)</span> <span class="o">{</span>
  <span class="n">preStart</span><span class="o">();</span>
<span class="o">}</span>

<span class="n">public</span> <span class="n">void</span> <span class="n">postStop</span><span class="o">()</span> <span class="o">{</span>
<span class="o">}</span>
</pre></div>
</div>
<p>The implementations shown above are the defaults provided by the <tt class="xref py py-class docutils literal"><span class="pre">UntypedActor</span></tt>
class.</p>
<div class="section" id="lifecycle-monitoring-aka-deathwatch">
<span id="deathwatch-java"></span><h3>Lifecycle Monitoring aka DeathWatch</h3>
<p>In order to be notified when another actor terminates (i.e. stops permanently,
not temporary failure and restart), an actor may register itself for reception
of the <tt class="xref py py-class docutils literal"><span class="pre">Terminated</span></tt> message dispatched by the other actor upon
termination (see <a class="reference internal" href="#stopping-actors">Stopping Actors</a>). This service is provided by the
<tt class="xref py py-class docutils literal"><span class="pre">DeathWatch</span></tt> component of the actor system.</p>
<p>Registering a monitor is easy (see fourth line, the rest is for demonstrating
the whole functionality):</p>
<div class="highlight-scala"><div class="highlight"><pre><span class="n">public</span> <span class="n">static</span> <span class="k">class</span> <span class="nc">WatchActor</span> <span class="k">extends</span> <span class="nc">UntypedActor</span> <span class="o">{</span>
  <span class="k">final</span> <span class="nc">ActorRef</span> <span class="n">child</span> <span class="k">=</span> <span class="k">this</span><span class="o">.</span><span class="n">getContext</span><span class="o">().</span><span class="n">actorOf</span><span class="o">(</span><span class="nc">Props</span><span class="o">.</span><span class="n">empty</span><span class="o">(),</span> <span class="s">&quot;child&quot;</span><span class="o">);</span>
  <span class="o">{</span>
    <span class="k">this</span><span class="o">.</span><span class="n">getContext</span><span class="o">().</span><span class="n">watch</span><span class="o">(</span><span class="n">child</span><span class="o">);</span> <span class="c1">// &lt;-- this is the only call needed for registration</span>
  <span class="o">}</span>
  <span class="nc">ActorRef</span> <span class="n">lastSender</span> <span class="k">=</span> <span class="n">getContext</span><span class="o">().</span><span class="n">system</span><span class="o">().</span><span class="n">deadLetters</span><span class="o">();</span>

  <span class="nd">@Override</span>
  <span class="n">public</span> <span class="n">void</span> <span class="n">onReceive</span><span class="o">(</span><span class="nc">Object</span> <span class="n">message</span><span class="o">)</span> <span class="o">{</span>
    <span class="k">if</span> <span class="o">(</span><span class="n">message</span><span class="o">.</span><span class="n">equals</span><span class="o">(</span><span class="s">&quot;kill&quot;</span><span class="o">))</span> <span class="o">{</span>
      <span class="n">getContext</span><span class="o">().</span><span class="n">stop</span><span class="o">(</span><span class="n">child</span><span class="o">);</span>
      <span class="n">lastSender</span> <span class="k">=</span> <span class="n">getSender</span><span class="o">();</span>
    <span class="o">}</span> <span class="k">else</span> <span class="k">if</span> <span class="o">(</span><span class="n">message</span> <span class="n">instanceof</span> <span class="nc">Terminated</span><span class="o">)</span> <span class="o">{</span>
      <span class="k">final</span> <span class="nc">Terminated</span> <span class="n">t</span> <span class="k">=</span> <span class="o">(</span><span class="nc">Terminated</span><span class="o">)</span> <span class="n">message</span><span class="o">;</span>
      <span class="k">if</span> <span class="o">(</span><span class="n">t</span><span class="o">.</span><span class="n">getActor</span><span class="o">()</span> <span class="o">==</span> <span class="n">child</span><span class="o">)</span> <span class="o">{</span>
        <span class="n">lastSender</span><span class="o">.</span><span class="n">tell</span><span class="o">(</span><span class="s">&quot;finished&quot;</span><span class="o">);</span>
      <span class="o">}</span>
    <span class="o">}</span> <span class="k">else</span> <span class="o">{</span>
      <span class="n">unhandled</span><span class="o">(</span><span class="n">message</span><span class="o">);</span>
    <span class="o">}</span>
  <span class="o">}</span>
<span class="o">}</span>
</pre></div>
</div>
<p>It should be noted that the <tt class="xref py py-class docutils literal"><span class="pre">Terminated</span></tt> message is generated
independent of the order in which registration and termination occur.
Registering multiple times does not necessarily lead to multiple messages being
generated, but there is no guarantee that only exactly one such message is
received: if termination of the watched actor has generated and queued the
message, and another registration is done before this message has been
processed, then a second message will be queued, because registering for
monitoring of an already terminated actor leads to the immediate generation of
the <tt class="xref py py-class docutils literal"><span class="pre">Terminated</span></tt> message.</p>
<p>It is also possible to deregister from watching another actor’s liveliness
using <tt class="docutils literal"><span class="pre">context.unwatch(target)</span></tt>, but obviously this cannot guarantee
non-reception of the <tt class="xref py py-class docutils literal"><span class="pre">Terminated</span></tt> message because that may already have
been queued.</p>
</div>
<div class="section" id="start-hook">
<h3>Start Hook</h3>
<p>Right after starting the actor, its <tt class="xref py py-meth docutils literal"><span class="pre">preStart</span></tt> method is invoked.</p>
<div class="highlight-scala"><div class="highlight"><pre><span class="nd">@Override</span>
<span class="n">public</span> <span class="n">void</span> <span class="n">preStart</span><span class="o">()</span> <span class="o">{</span>
  <span class="c1">// registering with other actors</span>
  <span class="n">someService</span><span class="o">.</span><span class="n">tell</span><span class="o">(</span><span class="nc">Register</span><span class="o">(</span><span class="n">getSelf</span><span class="o">());</span>
<span class="o">}</span>
</pre></div>
</div>
</div>
<div class="section" id="restart-hooks">
<h3>Restart Hooks</h3>
<p>All actors are supervised, i.e. linked to another actor with a fault
handling strategy. Actors will be restarted in case an exception is thrown while
processing a message. This restart involves the hooks mentioned above:</p>
<ol class="arabic simple">
<li>The old actor is informed by calling <tt class="xref py py-meth docutils literal"><span class="pre">preRestart</span></tt> with the exception
which caused the restart and the message which triggered that exception; the
latter may be <tt class="docutils literal"><span class="pre">None</span></tt> if the restart was not caused by processing a
message, e.g. when a supervisor does not trap the exception and is restarted
in turn by its supervisor. This method is the best place for cleaning up,
preparing hand-over to the fresh actor instance, etc.
By default it stops all children and calls <tt class="xref py py-meth docutils literal"><span class="pre">postStop</span></tt>.</li>
<li>The initial factory from the <tt class="docutils literal"><span class="pre">actorOf</span></tt> call is used
to produce the fresh instance.</li>
<li>The new actor’s <tt class="xref py py-meth docutils literal"><span class="pre">postRestart</span></tt> method is invoked with the exception
which caused the restart. By default the <tt class="xref py py-meth docutils literal"><span class="pre">preStart</span></tt>
is called, just as in the normal start-up case.</li>
</ol>
<p>An actor restart replaces only the actual actor object; the contents of the
mailbox is unaffected by the restart, so processing of messages will resume
after the <tt class="xref py py-meth docutils literal"><span class="pre">postRestart</span></tt> hook returns. The message
that triggered the exception will not be received again. Any message
sent to an actor while it is being restarted will be queued to its mailbox as
usual.</p>
</div>
<div class="section" id="stop-hook">
<h3>Stop Hook</h3>
<p>After stopping an actor, its <tt class="xref py py-meth docutils literal"><span class="pre">postStop</span></tt> hook is called, which may be used
e.g. for deregistering this actor from other services. This hook is guaranteed
to run after message queuing has been disabled for this actor, i.e. messages
sent to a stopped actor will be redirected to the <tt class="xref py py-obj docutils literal"><span class="pre">deadLetters</span></tt> of the
<tt class="xref py py-obj docutils literal"><span class="pre">ActorSystem</span></tt>.</p>
</div>
</div>
<div class="section" id="identifying-actors">
<h2>Identifying Actors</h2>
<p>As described in <a class="reference internal" href="../general/addressing.html#addressing"><em>Actor References, Paths and Addresses</em></a>, each actor has a unique logical path, which
is obtained by following the chain of actors from child to parent until
reaching the root of the actor system, and it has a physical path, which may
differ if the supervision chain includes any remote supervisors. These paths
are used by the system to look up actors, e.g. when a remote message is
received and the recipient is searched, but they are also useful more directly:
actors may look up other actors by specifying absolute or relative
paths—logical or physical—and receive back an <tt class="xref py py-class docutils literal"><span class="pre">ActorRef</span></tt> with the
result:</p>
<div class="highlight-scala"><div class="highlight"><pre><span class="n">getContext</span><span class="o">().</span><span class="n">actorFor</span><span class="o">(</span><span class="s">&quot;/user/serviceA/aggregator&quot;</span><span class="o">)</span> <span class="c1">// will look up this absolute path</span>
<span class="n">getContext</span><span class="o">().</span><span class="n">actorFor</span><span class="o">(</span><span class="s">&quot;../joe&quot;</span><span class="o">)</span>                    <span class="c1">// will look up sibling beneath same supervisor</span>
</pre></div>
</div>
<p>The supplied path is parsed as a <tt class="xref py py-class docutils literal"><span class="pre">java.net.URI</span></tt>, which basically means
that it is split on <tt class="docutils literal"><span class="pre">/</span></tt> into path elements. If the path starts with <tt class="docutils literal"><span class="pre">/</span></tt>, it
is absolute and the look-up starts at the root guardian (which is the parent of
<tt class="docutils literal"><span class="pre">&quot;/user&quot;</span></tt>); otherwise it starts at the current actor. If a path element equals
<tt class="docutils literal"><span class="pre">..</span></tt>, the look-up will take a step “up” towards the supervisor of the
currently traversed actor, otherwise it will step “down” to the named child.
It should be noted that the <tt class="docutils literal"><span class="pre">..</span></tt> in actor paths here always means the logical
structure, i.e. the supervisor.</p>
<p>If the path being looked up does not exist, a special actor reference is
returned which behaves like the actor system’s dead letter queue but retains
its identity (i.e. the path which was looked up).</p>
<p>Remote actor addresses may also be looked up, if remoting is enabled:</p>
<div class="highlight-scala"><div class="highlight"><pre><span class="n">getContext</span><span class="o">().</span><span class="n">actorFor</span><span class="o">(</span><span class="s">&quot;akka://app@otherhost:1234/user/serviceB&quot;</span><span class="o">)</span>
</pre></div>
</div>
<p>These look-ups return a (possibly remote) actor reference immediately, so you
will have to send to it and await a reply in order to verify that <tt class="docutils literal"><span class="pre">serviceB</span></tt>
is actually reachable and running. An example demonstrating actor look-up is
given in <a class="reference internal" href="remoting.html#remote-lookup-sample-java"><em>Remote Lookup</em></a>.</p>
</div>
<div class="section" id="messages-and-immutability">
<h2>Messages and immutability</h2>
<p><strong>IMPORTANT</strong>: Messages can be any kind of object but have to be
immutable. Akka can’t enforce immutability (yet) so this has to be by
convention.</p>
<p>Here is an example of an immutable message:</p>
<div class="highlight-scala"><div class="highlight"><pre><span class="n">public</span> <span class="k">class</span> <span class="nc">ImmutableMessage</span> <span class="o">{</span>
  <span class="k">private</span> <span class="k">final</span> <span class="n">int</span> <span class="n">sequenceNumber</span><span class="o">;</span>
  <span class="k">private</span> <span class="k">final</span> <span class="nc">List</span><span class="o">&lt;</span><span class="nc">String</span><span class="o">&gt;</span> <span class="n">values</span><span class="o">;</span>

  <span class="n">public</span> <span class="nc">ImmutableMessage</span><span class="o">(</span><span class="n">int</span> <span class="n">sequenceNumber</span><span class="o">,</span> <span class="nc">List</span><span class="o">&lt;</span><span class="nc">String</span><span class="o">&gt;</span> <span class="n">values</span><span class="o">)</span> <span class="o">{</span>
    <span class="k">this</span><span class="o">.</span><span class="n">sequenceNumber</span> <span class="k">=</span> <span class="n">sequenceNumber</span><span class="o">;</span>
    <span class="k">this</span><span class="o">.</span><span class="n">values</span> <span class="k">=</span> <span class="nc">Collections</span><span class="o">.</span><span class="n">unmodifiableList</span><span class="o">(</span><span class="k">new</span> <span class="nc">ArrayList</span><span class="o">&lt;</span><span class="nc">String</span><span class="o">&gt;(</span><span class="n">values</span><span class="o">));</span>
  <span class="o">}</span>

  <span class="n">public</span> <span class="n">int</span> <span class="n">getSequenceNumber</span><span class="o">()</span> <span class="o">{</span>
    <span class="k">return</span> <span class="n">sequenceNumber</span><span class="o">;</span>
  <span class="o">}</span>

  <span class="n">public</span> <span class="nc">List</span><span class="o">&lt;</span><span class="nc">String</span><span class="o">&gt;</span> <span class="n">getValues</span><span class="o">()</span> <span class="o">{</span>
    <span class="k">return</span> <span class="n">values</span><span class="o">;</span>
  <span class="o">}</span>
<span class="o">}</span>
</pre></div>
</div>
</div>
<div class="section" id="send-messages">
<h2>Send messages</h2>
<p>Messages are sent to an Actor through one of the following methods.</p>
<ul class="simple">
<li><tt class="docutils literal"><span class="pre">tell</span></tt> means “fire-and-forget”, e.g. send a message asynchronously and return
immediately.</li>
<li><tt class="docutils literal"><span class="pre">ask</span></tt> sends a message asynchronously and returns a <tt class="xref py py-class docutils literal"><span class="pre">Future</span></tt>
representing a possible reply.</li>
</ul>
<p>Message ordering is guaranteed on a per-sender basis.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">There are performance implications of using <tt class="docutils literal"><span class="pre">ask</span></tt> since something needs to
keep track of when it times out, there needs to be something that bridges
a <tt class="docutils literal"><span class="pre">Promise</span></tt> into an <tt class="docutils literal"><span class="pre">ActorRef</span></tt> and it also needs to be reachable through
remoting. So always prefer <tt class="docutils literal"><span class="pre">tell</span></tt> for performance, and only <tt class="docutils literal"><span class="pre">ask</span></tt> if you must.</p>
</div>
<p>In all these methods you have the option of passing along your own <tt class="docutils literal"><span class="pre">ActorRef</span></tt>.
Make it a practice of doing so because it will allow the receiver actors to be able to respond
to your message, since the sender reference is sent along with the message.</p>
<div class="section" id="tell-fire-forget">
<h3>Tell: Fire-forget</h3>
<p>This is the preferred way of sending messages. No blocking waiting for a
message. This gives the best concurrency and scalability characteristics.</p>
<div class="highlight-java"><div class="highlight"><pre><span class="n">actor</span><span class="o">.</span><span class="na">tell</span><span class="o">(</span><span class="s">&quot;Hello&quot;</span><span class="o">);</span>
</pre></div>
</div>
<p>Or with the sender reference passed along with the message and available to the receiving Actor
in its <tt class="docutils literal"><span class="pre">getSender:</span> <span class="pre">ActorRef</span></tt> member field. The target actor can use this
to reply to the original sender, by using <tt class="docutils literal"><span class="pre">getSender().tell(replyMsg)</span></tt>.</p>
<div class="highlight-java"><div class="highlight"><pre><span class="n">actor</span><span class="o">.</span><span class="na">tell</span><span class="o">(</span><span class="s">&quot;Hello&quot;</span><span class="o">,</span> <span class="n">getSelf</span><span class="o">());</span>
</pre></div>
</div>
<p>If invoked without the sender parameter the sender will be
<tt class="xref py py-obj docutils literal"><span class="pre">deadLetters</span></tt> actor reference in the target actor.</p>
</div>
<div class="section" id="ask-send-and-receive-future">
<h3>Ask: Send-And-Receive-Future</h3>
<p>The <tt class="docutils literal"><span class="pre">ask</span></tt> pattern involves actors as well as futures, hence it is offered as
a use pattern rather than a method on <tt class="xref py py-class docutils literal"><span class="pre">ActorRef</span></tt>:</p>
<div class="highlight-scala"><div class="highlight"><pre><span class="k">import</span> <span class="nn">static</span> <span class="n">akka</span><span class="o">.</span><span class="n">pattern</span><span class="o">.</span><span class="nc">Patterns</span><span class="o">.</span><span class="n">ask</span><span class="o">;</span>
<span class="k">import</span> <span class="nn">static</span> <span class="n">akka</span><span class="o">.</span><span class="n">pattern</span><span class="o">.</span><span class="nc">Patterns</span><span class="o">.</span><span class="n">pipe</span><span class="o">;</span>
<span class="k">import</span> <span class="nn">akka.dispatch.Future</span><span class="o">;</span>
<span class="k">import</span> <span class="nn">akka.dispatch.Futures</span><span class="o">;</span>
<span class="k">import</span> <span class="nn">akka.util.Duration</span><span class="o">;</span>
<span class="k">import</span> <span class="nn">akka.util.Timeout</span><span class="o">;</span>
<span class="k">import</span> <span class="nn">java.util.concurrent.TimeUnit</span><span class="o">;</span>
<span class="k">import</span> <span class="nn">java.util.ArrayList</span><span class="o">;</span>
</pre></div>
</div>
<div class="highlight-scala"><div class="highlight"><pre><span class="k">final</span> <span class="nc">Timeout</span> <span class="n">t</span> <span class="k">=</span> <span class="k">new</span> <span class="nc">Timeout</span><span class="o">(</span><span class="nc">Duration</span><span class="o">.</span><span class="n">create</span><span class="o">(</span><span class="mi">5</span><span class="o">,</span> <span class="nc">TimeUnit</span><span class="o">.</span><span class="nc">SECONDS</span><span class="o">));</span>

<span class="k">final</span> <span class="nc">ArrayList</span><span class="o">&lt;</span><span class="nc">Future</span><span class="o">&lt;</span><span class="nc">Object</span><span class="o">&gt;&gt;</span> <span class="n">futures</span> <span class="k">=</span> <span class="k">new</span> <span class="nc">ArrayList</span><span class="o">&lt;</span><span class="nc">Future</span><span class="o">&lt;</span><span class="nc">Object</span><span class="o">&gt;&gt;();</span>
<span class="n">futures</span><span class="o">.</span><span class="n">add</span><span class="o">(</span><span class="n">ask</span><span class="o">(</span><span class="n">actorA</span><span class="o">,</span> <span class="s">&quot;request&quot;</span><span class="o">,</span> <span class="mi">1000</span><span class="o">));</span> <span class="c1">// using 1000ms timeout</span>
<span class="n">futures</span><span class="o">.</span><span class="n">add</span><span class="o">(</span><span class="n">ask</span><span class="o">(</span><span class="n">actorB</span><span class="o">,</span> <span class="s">&quot;reqeest&quot;</span><span class="o">,</span> <span class="n">t</span><span class="o">));</span> <span class="c1">// using timeout from above</span>

<span class="k">final</span> <span class="nc">Future</span><span class="o">&lt;</span><span class="nc">Iterable</span><span class="o">&lt;</span><span class="nc">Object</span><span class="o">&gt;&gt;</span> <span class="n">aggregate</span> <span class="k">=</span> <span class="nc">Futures</span><span class="o">.</span><span class="n">sequence</span><span class="o">(</span><span class="n">futures</span><span class="o">,</span> <span class="n">system</span><span class="o">.</span><span class="n">dispatcher</span><span class="o">());</span>

<span class="k">final</span> <span class="nc">Future</span><span class="o">&lt;</span><span class="nc">Result</span><span class="o">&gt;</span> <span class="n">transformed</span> <span class="k">=</span> <span class="n">aggregate</span><span class="o">.</span><span class="n">map</span><span class="o">(</span><span class="k">new</span> <span class="nc">Mapper</span><span class="o">&lt;</span><span class="nc">Iterable</span><span class="o">&lt;</span><span class="nc">Object</span><span class="o">&gt;,</span> <span class="nc">Result</span><span class="o">&gt;()</span> <span class="o">{</span>
  <span class="n">public</span> <span class="nc">Result</span> <span class="n">apply</span><span class="o">(</span><span class="nc">Iterable</span><span class="o">&lt;</span><span class="nc">Object</span><span class="o">&gt;</span> <span class="n">coll</span><span class="o">)</span> <span class="o">{</span>
    <span class="k">final</span> <span class="nc">Iterator</span><span class="o">&lt;</span><span class="nc">Object</span><span class="o">&gt;</span> <span class="n">it</span> <span class="k">=</span> <span class="n">coll</span><span class="o">.</span><span class="n">iterator</span><span class="o">();</span>
    <span class="k">final</span> <span class="nc">String</span> <span class="n">s</span> <span class="k">=</span> <span class="o">(</span><span class="nc">String</span><span class="o">)</span> <span class="n">it</span><span class="o">.</span><span class="n">next</span><span class="o">();</span>
    <span class="k">final</span> <span class="n">int</span> <span class="n">x</span> <span class="k">=</span> <span class="o">(</span><span class="nc">Integer</span><span class="o">)</span> <span class="n">it</span><span class="o">.</span><span class="n">next</span><span class="o">();</span>
    <span class="k">return</span> <span class="k">new</span> <span class="nc">Result</span><span class="o">(</span><span class="n">x</span><span class="o">,</span> <span class="n">s</span><span class="o">);</span>
  <span class="o">}</span>
<span class="o">});</span>

<span class="n">pipe</span><span class="o">(</span><span class="n">transformed</span><span class="o">).</span><span class="n">to</span><span class="o">(</span><span class="n">actorC</span><span class="o">);</span>
</pre></div>
</div>
<p>This example demonstrates <tt class="docutils literal"><span class="pre">ask</span></tt> together with the <tt class="docutils literal"><span class="pre">pipe</span></tt> pattern on
futures, because this is likely to be a common combination. Please note that
all of the above is completely non-blocking and asynchronous: <tt class="docutils literal"><span class="pre">ask</span></tt> produces
a <tt class="xref py py-class docutils literal"><span class="pre">Future</span></tt>, two of which are composed into a new future using the
<tt class="xref py py-meth docutils literal"><span class="pre">Futures.sequence</span></tt> and <tt class="xref py py-meth docutils literal"><span class="pre">map</span></tt> methods and then <tt class="docutils literal"><span class="pre">pipe</span></tt> installs
an <tt class="docutils literal"><span class="pre">onComplete</span></tt>-handler on the future to effect the submission of the
aggregated <tt class="xref py py-class docutils literal"><span class="pre">Result</span></tt> to another actor.</p>
<p>Using <tt class="docutils literal"><span class="pre">ask</span></tt> will send a message to the receiving Actor as with <tt class="docutils literal"><span class="pre">tell</span></tt>, and
the receiving actor must reply with <tt class="docutils literal"><span class="pre">getSender().tell(reply)</span></tt> in order to
complete the returned <tt class="xref py py-class docutils literal"><span class="pre">Future</span></tt> with a value. The <tt class="docutils literal"><span class="pre">ask</span></tt> operation
involves creating an internal actor for handling this reply, which needs to
have a timeout after which it is destroyed in order not to leak resources; see
more below.</p>
<p>To complete the future with an exception you need send a Failure message to the sender.
This is <em>not done automatically</em> when an actor throws an exception while processing a
message.</p>
<div class="highlight-scala"><div class="highlight"><pre><span class="k">try</span> <span class="o">{</span>
  <span class="nc">String</span> <span class="n">result</span> <span class="k">=</span> <span class="n">operation</span><span class="o">();</span>
  <span class="n">getSender</span><span class="o">().</span><span class="n">tell</span><span class="o">(</span><span class="n">result</span><span class="o">);</span>
<span class="o">}</span> <span class="k">catch</span> <span class="o">(</span><span class="nc">Exception</span> <span class="n">e</span><span class="o">)</span> <span class="o">{</span>
  <span class="n">getSender</span><span class="o">().</span><span class="n">tell</span><span class="o">(</span><span class="k">new</span> <span class="n">akka</span><span class="o">.</span><span class="n">actor</span><span class="o">.</span><span class="nc">Status</span><span class="o">.</span><span class="nc">Failure</span><span class="o">(</span><span class="n">e</span><span class="o">));</span>
  <span class="k">throw</span> <span class="n">e</span><span class="o">;</span>
<span class="o">}</span>
</pre></div>
</div>
<p>If the actor does not complete the future, it will expire after the timeout period,
specified as parameter to the <tt class="docutils literal"><span class="pre">ask</span></tt> method; this will complete the
<tt class="xref py py-class docutils literal"><span class="pre">Future</span></tt> with an <tt class="xref py py-class docutils literal"><span class="pre">AskTimeoutException</span></tt>.</p>
<p>See <a class="reference internal" href="futures.html#futures-java"><em>Futures (Java)</em></a> for more information on how to await or query a
future.</p>
<p>The <tt class="docutils literal"><span class="pre">onComplete</span></tt>, <tt class="docutils literal"><span class="pre">onResult</span></tt>, or <tt class="docutils literal"><span class="pre">onTimeout</span></tt> methods of the <tt class="docutils literal"><span class="pre">Future</span></tt> can be
used to register a callback to get a notification when the Future completes.
Gives you a way to avoid blocking.</p>
<div class="admonition warning">
<p class="first admonition-title">Warning</p>
<p class="last">When using future callbacks, inside actors you need to carefully avoid closing over
the containing actor’s reference, i.e. do not call methods or access mutable state
on the enclosing actor from within the callback. This would break the actor
encapsulation and may introduce synchronization bugs and race conditions because
the callback will be scheduled concurrently to the enclosing actor. Unfortunately
there is not yet a way to detect these illegal accesses at compile time. See also:
<a class="reference internal" href="../general/jmm.html#jmm-shared-state"><em>Actors and shared mutable state</em></a></p>
</div>
</div>
<div class="section" id="forward-message">
<h3>Forward message</h3>
<p>You can forward a message from one actor to another. This means that the
original sender address/reference is maintained even though the message is going
through a &#8216;mediator&#8217;. This can be useful when writing actors that work as
routers, load-balancers, replicators etc.
You need to pass along your context variable as well.</p>
<div class="highlight-java"><div class="highlight"><pre><span class="n">myActor</span><span class="o">.</span><span class="na">forward</span><span class="o">(</span><span class="n">message</span><span class="o">,</span> <span class="n">getContext</span><span class="o">());</span>
</pre></div>
</div>
</div>
</div>
<div class="section" id="receive-messages">
<h2>Receive messages</h2>
<p>When an actor receives a message it is passed into the <tt class="docutils literal"><span class="pre">onReceive</span></tt> method, this is
an abstract method on the <tt class="docutils literal"><span class="pre">UntypedActor</span></tt> base class that needs to be defined.</p>
<p>Here is an example:</p>
<div class="highlight-scala"><div class="highlight"><pre><span class="k">import</span> <span class="nn">akka.actor.UntypedActor</span><span class="o">;</span>
<span class="k">import</span> <span class="nn">akka.event.Logging</span><span class="o">;</span>
<span class="k">import</span> <span class="nn">akka.event.LoggingAdapter</span><span class="o">;</span>

<span class="n">public</span> <span class="k">class</span> <span class="nc">MyUntypedActor</span> <span class="k">extends</span> <span class="nc">UntypedActor</span> <span class="o">{</span>
  <span class="nc">LoggingAdapter</span> <span class="n">log</span> <span class="k">=</span> <span class="nc">Logging</span><span class="o">.</span><span class="n">getLogger</span><span class="o">(</span><span class="n">getContext</span><span class="o">().</span><span class="n">system</span><span class="o">(),</span> <span class="k">this</span><span class="o">);</span>

  <span class="n">public</span> <span class="n">void</span> <span class="n">onReceive</span><span class="o">(</span><span class="nc">Object</span> <span class="n">message</span><span class="o">)</span> <span class="n">throws</span> <span class="nc">Exception</span> <span class="o">{</span>
    <span class="k">if</span> <span class="o">(</span><span class="n">message</span> <span class="n">instanceof</span> <span class="nc">String</span><span class="o">)</span>
      <span class="n">log</span><span class="o">.</span><span class="n">info</span><span class="o">(</span><span class="s">&quot;Received String message: {}&quot;</span><span class="o">,</span> <span class="n">message</span><span class="o">);</span>
    <span class="k">else</span>
      <span class="n">unhandled</span><span class="o">(</span><span class="n">message</span><span class="o">);</span>
  <span class="o">}</span>
<span class="o">}</span>
</pre></div>
</div>
<p>An alternative to using if-instanceof checks is to use <a class="reference external" href="http://commons.apache.org/beanutils/api/org/apache/commons/beanutils/MethodUtils.html#invokeMethod(java.lang.Object,%20java.lang.String,%20java.lang.Object)">Apache Commons MethodUtils</a>
to invoke a named method whose parameter type matches the message type.</p>
</div>
<div class="section" id="reply-to-messages">
<span id="untypedactor-reply"></span><h2>Reply to messages</h2>
<p>If you want to have a handle for replying to a message, you can use
<tt class="docutils literal"><span class="pre">getSender()</span></tt>, which gives you an ActorRef. You can reply by sending to
that ActorRef with <tt class="docutils literal"><span class="pre">getSender().tell(replyMsg)</span></tt>. You can also store the ActorRef
for replying later, or passing on to other actors. If there is no sender (a
message was sent without an actor or future context) then the sender
defaults to a &#8216;dead-letter&#8217; actor ref.</p>
<div class="highlight-java"><div class="highlight"><pre><span class="kd">public</span> <span class="kt">void</span> <span class="nf">onReceive</span><span class="o">(</span><span class="n">Object</span> <span class="n">request</span><span class="o">)</span> <span class="o">{</span>
  <span class="n">String</span> <span class="n">result</span> <span class="o">=</span> <span class="n">process</span><span class="o">(</span><span class="n">request</span><span class="o">);</span>
  <span class="n">getSender</span><span class="o">().</span><span class="na">tell</span><span class="o">(</span><span class="n">result</span><span class="o">);</span>       <span class="c1">// will have dead-letter actor as default</span>
<span class="o">}</span>
</pre></div>
</div>
</div>
<div class="section" id="initial-receive-timeout">
<h2>Initial receive timeout</h2>
<p>A timeout mechanism can be used to receive a message when no initial message is
received within a certain time. To receive this timeout you have to set the
<tt class="docutils literal"><span class="pre">receiveTimeout</span></tt> property and declare handing for the ReceiveTimeout
message.</p>
<div class="highlight-scala"><div class="highlight"><pre><span class="k">import</span> <span class="nn">akka.actor.Actors</span><span class="o">;</span>
<span class="k">import</span> <span class="nn">akka.actor.ReceiveTimeout</span><span class="o">;</span>
<span class="k">import</span> <span class="nn">akka.actor.UntypedActor</span><span class="o">;</span>
<span class="k">import</span> <span class="nn">akka.util.Duration</span><span class="o">;</span>

<span class="n">public</span> <span class="k">class</span> <span class="nc">MyReceivedTimeoutUntypedActor</span> <span class="k">extends</span> <span class="nc">UntypedActor</span> <span class="o">{</span>

  <span class="n">public</span> <span class="nc">MyReceivedTimeoutUntypedActor</span><span class="o">()</span> <span class="o">{</span>
    <span class="n">getContext</span><span class="o">().</span><span class="n">setReceiveTimeout</span><span class="o">(</span><span class="nc">Duration</span><span class="o">.</span><span class="n">parse</span><span class="o">(</span><span class="s">&quot;30 seconds&quot;</span><span class="o">));</span>
  <span class="o">}</span>

  <span class="n">public</span> <span class="n">void</span> <span class="n">onReceive</span><span class="o">(</span><span class="nc">Object</span> <span class="n">message</span><span class="o">)</span> <span class="o">{</span>
    <span class="k">if</span> <span class="o">(</span><span class="n">message</span><span class="o">.</span><span class="n">equals</span><span class="o">(</span><span class="s">&quot;Hello&quot;</span><span class="o">))</span> <span class="o">{</span>
      <span class="n">getSender</span><span class="o">().</span><span class="n">tell</span><span class="o">(</span><span class="s">&quot;Hello world&quot;</span><span class="o">);</span>
    <span class="o">}</span> <span class="k">else</span> <span class="k">if</span> <span class="o">(</span><span class="n">message</span> <span class="o">==</span> <span class="nc">Actors</span><span class="o">.</span><span class="n">receiveTimeout</span><span class="o">())</span> <span class="o">{</span>
      <span class="k">throw</span> <span class="k">new</span> <span class="nc">RuntimeException</span><span class="o">(</span><span class="s">&quot;received timeout&quot;</span><span class="o">);</span>
    <span class="o">}</span> <span class="k">else</span> <span class="o">{</span>
      <span class="n">unhandled</span><span class="o">(</span><span class="n">message</span><span class="o">);</span>
    <span class="o">}</span>
  <span class="o">}</span>
<span class="o">}</span>
</pre></div>
</div>
</div>
<div class="section" id="stopping-actors">
<span id="stopping-actors-java"></span><h2>Stopping actors</h2>
<p>Actors are stopped by invoking the <tt class="xref py py-meth docutils literal"><span class="pre">stop</span></tt> method of a <tt class="docutils literal"><span class="pre">ActorRefFactory</span></tt>,
i.e. <tt class="docutils literal"><span class="pre">ActorContext</span></tt> or <tt class="docutils literal"><span class="pre">ActorSystem</span></tt>. Typically the context is used for stopping
child actors and the system for stopping top level actors. The actual termination of
the actor is performed asynchronously, i.e. <tt class="xref py py-meth docutils literal"><span class="pre">stop</span></tt> may return before the actor is
stopped.</p>
<p>Processing of the current message, if any, will continue before the actor is stopped,
but additional messages in the mailbox will not be processed. By default these
messages are sent to the <tt class="xref py py-obj docutils literal"><span class="pre">deadLetters</span></tt> of the <tt class="xref py py-obj docutils literal"><span class="pre">ActorSystem</span></tt>, but that
depends on the mailbox implementation.</p>
<p>Termination of an actor proceeds in two steps: first the actor suspends its
mailbox processing and sends a stop command to all its children, then it keeps
processing the termination messages from its children until the last one is
gone, finally terminating itself (invoking <tt class="xref py py-meth docutils literal"><span class="pre">postStop</span></tt>, dumping mailbox,
publishing <tt class="xref py py-class docutils literal"><span class="pre">Terminated</span></tt> on the <a class="reference internal" href="#deathwatch-java"><em>DeathWatch</em></a>, telling
its supervisor). This procedure ensures that actor system sub-trees terminate
in an orderly fashion, propagating the stop command to the leaves and
collecting their confirmation back to the stopped supervisor. If one of the
actors does not respond (i.e. processing a message for extended periods of time
and therefore not receiving the stop command), this whole process will be
stuck.</p>
<p>Upon <tt class="xref py py-meth docutils literal"><span class="pre">ActorSystem.shutdown</span></tt>, the system guardian actors will be
stopped, and the aforementioned process will ensure proper termination of the
whole system.</p>
<p>The <tt class="xref py py-meth docutils literal"><span class="pre">postStop</span></tt> hook is invoked after an actor is fully stopped. This
enables cleaning up of resources:</p>
<div class="highlight-java"><div class="highlight"><pre><span class="nd">@Override</span>
<span class="kd">public</span> <span class="kt">void</span> <span class="nf">postStop</span><span class="o">()</span> <span class="o">{</span>
  <span class="c1">// close some file or database connection</span>
<span class="o">}</span>
</pre></div>
</div>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">Since stopping an actor is asynchronous, you cannot immediately reuse the
name of the child you just stopped; this will result in an
<tt class="xref py py-class docutils literal"><span class="pre">InvalidActorNameException</span></tt>. Instead, <tt class="xref py py-meth docutils literal"><span class="pre">watch</span></tt> the terminating
actor and create its replacement in response to the <tt class="xref py py-class docutils literal"><span class="pre">Terminated</span></tt>
message which will eventually arrive.</p>
</div>
<div class="section" id="poisonpill">
<h3>PoisonPill</h3>
<p>You can also send an actor the <tt class="docutils literal"><span class="pre">akka.actor.PoisonPill</span></tt> message, which will
stop the actor when the message is processed. <tt class="docutils literal"><span class="pre">PoisonPill</span></tt> is enqueued as
ordinary messages and will be handled after messages that were already queued
in the mailbox.</p>
<p>Use it like this:</p>
<div class="highlight-scala"><div class="highlight"><pre><span class="k">import</span> <span class="nn">static</span> <span class="n">akka</span><span class="o">.</span><span class="n">actor</span><span class="o">.</span><span class="nc">Actors</span><span class="o">.*;</span>
    <span class="n">myActor</span><span class="o">.</span><span class="n">tell</span><span class="o">(</span><span class="n">poisonPill</span><span class="o">());</span>
</pre></div>
</div>
</div>
<div class="section" id="graceful-stop">
<h3>Graceful Stop</h3>
<p><tt class="xref py py-meth docutils literal"><span class="pre">gracefulStop</span></tt> is useful if you need to wait for termination or compose ordered
termination of several actors:</p>
<div class="highlight-scala"><div class="highlight"><pre><span class="k">import</span> <span class="nn">static</span> <span class="n">akka</span><span class="o">.</span><span class="n">pattern</span><span class="o">.</span><span class="nc">Patterns</span><span class="o">.</span><span class="n">gracefulStop</span><span class="o">;</span>
<span class="k">import</span> <span class="nn">akka.dispatch.Future</span><span class="o">;</span>
<span class="k">import</span> <span class="nn">akka.dispatch.Await</span><span class="o">;</span>
<span class="k">import</span> <span class="nn">akka.util.Duration</span><span class="o">;</span>
<span class="k">import</span> <span class="nn">akka.actor.ActorTimeoutException</span><span class="o">;</span>

    <span class="k">try</span> <span class="o">{</span>
      <span class="nc">Future</span><span class="o">&lt;</span><span class="nc">Boolean</span><span class="o">&gt;</span> <span class="n">stopped</span> <span class="k">=</span> <span class="n">gracefulStop</span><span class="o">(</span><span class="n">actorRef</span><span class="o">,</span> <span class="nc">Duration</span><span class="o">.</span><span class="n">create</span><span class="o">(</span><span class="mi">5</span><span class="o">,</span> <span class="nc">TimeUnit</span><span class="o">.</span><span class="nc">SECONDS</span><span class="o">),</span> <span class="n">system</span><span class="o">);</span>
      <span class="nc">Await</span><span class="o">.</span><span class="n">result</span><span class="o">(</span><span class="n">stopped</span><span class="o">,</span> <span class="nc">Duration</span><span class="o">.</span><span class="n">create</span><span class="o">(</span><span class="mi">6</span><span class="o">,</span> <span class="nc">TimeUnit</span><span class="o">.</span><span class="nc">SECONDS</span><span class="o">));</span>
      <span class="c1">// the actor has been stopped</span>
    <span class="o">}</span> <span class="k">catch</span> <span class="o">(</span><span class="nc">ActorTimeoutException</span> <span class="n">e</span><span class="o">)</span> <span class="o">{</span>
      <span class="c1">// the actor wasn&#39;t stopped within 5 seconds</span>
    <span class="o">}</span>
</pre></div>
</div>
</div>
</div>
<div class="section" id="hotswap">
<span id="untypedactor-hotswap"></span><h2>HotSwap</h2>
<div class="section" id="upgrade">
<h3>Upgrade</h3>
<p>Akka supports hotswapping the Actor’s message loop (e.g. its implementation) at
runtime. Use the <tt class="docutils literal"><span class="pre">getContext().become</span></tt> method from within the Actor.
The hotswapped code is kept in a Stack which can be pushed and popped.</p>
<div class="admonition warning">
<p class="first admonition-title">Warning</p>
<p class="last">Please note that the actor will revert to its original behavior when restarted by its Supervisor.</p>
</div>
<p>To hotswap the Actor using <tt class="docutils literal"><span class="pre">getContext().become</span></tt>:</p>
<div class="highlight-scala"><div class="highlight"><pre><span class="k">import</span> <span class="nn">akka.japi.Procedure</span><span class="o">;</span>
  <span class="n">public</span> <span class="n">static</span> <span class="k">class</span> <span class="nc">HotSwapActor</span> <span class="k">extends</span> <span class="nc">UntypedActor</span> <span class="o">{</span>

    <span class="nc">Procedure</span><span class="o">&lt;</span><span class="nc">Object</span><span class="o">&gt;</span> <span class="n">angry</span> <span class="k">=</span> <span class="k">new</span> <span class="nc">Procedure</span><span class="o">&lt;</span><span class="nc">Object</span><span class="o">&gt;()</span> <span class="o">{</span>
      <span class="nd">@Override</span>
      <span class="n">public</span> <span class="n">void</span> <span class="n">apply</span><span class="o">(</span><span class="nc">Object</span> <span class="n">message</span><span class="o">)</span> <span class="o">{</span>
        <span class="k">if</span> <span class="o">(</span><span class="n">message</span><span class="o">.</span><span class="n">equals</span><span class="o">(</span><span class="s">&quot;foo&quot;</span><span class="o">))</span> <span class="o">{</span>
          <span class="n">getSender</span><span class="o">().</span><span class="n">tell</span><span class="o">(</span><span class="s">&quot;I am already angry?&quot;</span><span class="o">);</span>
        <span class="o">}</span> <span class="k">else</span> <span class="k">if</span> <span class="o">(</span><span class="n">message</span><span class="o">.</span><span class="n">equals</span><span class="o">(</span><span class="s">&quot;foo&quot;</span><span class="o">))</span> <span class="o">{</span>
          <span class="n">getContext</span><span class="o">().</span><span class="n">become</span><span class="o">(</span><span class="n">happy</span><span class="o">);</span>
        <span class="o">}</span>
      <span class="o">}</span>
    <span class="o">};</span>

    <span class="nc">Procedure</span><span class="o">&lt;</span><span class="nc">Object</span><span class="o">&gt;</span> <span class="n">happy</span> <span class="k">=</span> <span class="k">new</span> <span class="nc">Procedure</span><span class="o">&lt;</span><span class="nc">Object</span><span class="o">&gt;()</span> <span class="o">{</span>
      <span class="nd">@Override</span>
      <span class="n">public</span> <span class="n">void</span> <span class="n">apply</span><span class="o">(</span><span class="nc">Object</span> <span class="n">message</span><span class="o">)</span> <span class="o">{</span>
        <span class="k">if</span> <span class="o">(</span><span class="n">message</span><span class="o">.</span><span class="n">equals</span><span class="o">(</span><span class="s">&quot;bar&quot;</span><span class="o">))</span> <span class="o">{</span>
          <span class="n">getSender</span><span class="o">().</span><span class="n">tell</span><span class="o">(</span><span class="s">&quot;I am already happy :-)&quot;</span><span class="o">);</span>
        <span class="o">}</span> <span class="k">else</span> <span class="k">if</span> <span class="o">(</span><span class="n">message</span><span class="o">.</span><span class="n">equals</span><span class="o">(</span><span class="s">&quot;foo&quot;</span><span class="o">))</span> <span class="o">{</span>
          <span class="n">getContext</span><span class="o">().</span><span class="n">become</span><span class="o">(</span><span class="n">angry</span><span class="o">);</span>
        <span class="o">}</span>
      <span class="o">}</span>
    <span class="o">};</span>

    <span class="n">public</span> <span class="n">void</span> <span class="n">onReceive</span><span class="o">(</span><span class="nc">Object</span> <span class="n">message</span><span class="o">)</span> <span class="o">{</span>
      <span class="k">if</span> <span class="o">(</span><span class="n">message</span><span class="o">.</span><span class="n">equals</span><span class="o">(</span><span class="s">&quot;bar&quot;</span><span class="o">))</span> <span class="o">{</span>
        <span class="n">getContext</span><span class="o">().</span><span class="n">become</span><span class="o">(</span><span class="n">angry</span><span class="o">);</span>
      <span class="o">}</span> <span class="k">else</span> <span class="k">if</span> <span class="o">(</span><span class="n">message</span><span class="o">.</span><span class="n">equals</span><span class="o">(</span><span class="s">&quot;foo&quot;</span><span class="o">))</span> <span class="o">{</span>
        <span class="n">getContext</span><span class="o">().</span><span class="n">become</span><span class="o">(</span><span class="n">happy</span><span class="o">);</span>
      <span class="o">}</span> <span class="k">else</span> <span class="o">{</span>
        <span class="n">unhandled</span><span class="o">(</span><span class="n">message</span><span class="o">);</span>
      <span class="o">}</span>
    <span class="o">}</span>
  <span class="o">}</span>
</pre></div>
</div>
<p>The <tt class="docutils literal"><span class="pre">become</span></tt> method is useful for many different things, such as to implement
a Finite State Machine (FSM).</p>
<p>Here is another little cute example of <tt class="docutils literal"><span class="pre">become</span></tt> and <tt class="docutils literal"><span class="pre">unbecome</span></tt> in action:</p>
<div class="highlight-scala"><div class="highlight"><pre><span class="n">public</span> <span class="k">class</span> <span class="nc">UntypedActorSwapper</span> <span class="o">{</span>

  <span class="n">public</span> <span class="n">static</span> <span class="k">class</span> <span class="nc">Swap</span> <span class="o">{</span>
    <span class="n">public</span> <span class="n">static</span> <span class="nc">Swap</span> <span class="nc">SWAP</span> <span class="k">=</span> <span class="k">new</span> <span class="nc">Swap</span><span class="o">();</span>

    <span class="k">private</span> <span class="nc">Swap</span><span class="o">()</span> <span class="o">{</span>
    <span class="o">}</span>
  <span class="o">}</span>

  <span class="n">public</span> <span class="n">static</span> <span class="k">class</span> <span class="nc">Swapper</span> <span class="k">extends</span> <span class="nc">UntypedActor</span> <span class="o">{</span>
    <span class="nc">LoggingAdapter</span> <span class="n">log</span> <span class="k">=</span> <span class="nc">Logging</span><span class="o">.</span><span class="n">getLogger</span><span class="o">(</span><span class="n">getContext</span><span class="o">().</span><span class="n">system</span><span class="o">(),</span> <span class="k">this</span><span class="o">);</span>

    <span class="n">public</span> <span class="n">void</span> <span class="n">onReceive</span><span class="o">(</span><span class="nc">Object</span> <span class="n">message</span><span class="o">)</span> <span class="o">{</span>
      <span class="k">if</span> <span class="o">(</span><span class="n">message</span> <span class="o">==</span> <span class="nc">SWAP</span><span class="o">)</span> <span class="o">{</span>
        <span class="n">log</span><span class="o">.</span><span class="n">info</span><span class="o">(</span><span class="s">&quot;Hi&quot;</span><span class="o">);</span>
        <span class="n">getContext</span><span class="o">().</span><span class="n">become</span><span class="o">(</span><span class="k">new</span> <span class="nc">Procedure</span><span class="o">&lt;</span><span class="nc">Object</span><span class="o">&gt;()</span> <span class="o">{</span>
          <span class="nd">@Override</span>
          <span class="n">public</span> <span class="n">void</span> <span class="n">apply</span><span class="o">(</span><span class="nc">Object</span> <span class="n">message</span><span class="o">)</span> <span class="o">{</span>
            <span class="n">log</span><span class="o">.</span><span class="n">info</span><span class="o">(</span><span class="s">&quot;Ho&quot;</span><span class="o">);</span>
            <span class="n">getContext</span><span class="o">().</span><span class="n">unbecome</span><span class="o">();</span> <span class="c1">// resets the latest &#39;become&#39; (just for fun)</span>
          <span class="o">}</span>
        <span class="o">});</span>
      <span class="o">}</span> <span class="k">else</span> <span class="o">{</span>
        <span class="n">unhandled</span><span class="o">(</span><span class="n">message</span><span class="o">);</span>
      <span class="o">}</span>
    <span class="o">}</span>
  <span class="o">}</span>

  <span class="n">public</span> <span class="n">static</span> <span class="n">void</span> <span class="n">main</span><span class="o">(</span><span class="nc">String</span><span class="o">...</span> <span class="n">args</span><span class="o">)</span> <span class="o">{</span>
    <span class="nc">ActorSystem</span> <span class="n">system</span> <span class="k">=</span> <span class="nc">ActorSystem</span><span class="o">.</span><span class="n">create</span><span class="o">(</span><span class="s">&quot;MySystem&quot;</span><span class="o">);</span>
    <span class="nc">ActorRef</span> <span class="n">swap</span> <span class="k">=</span> <span class="n">system</span><span class="o">.</span><span class="n">actorOf</span><span class="o">(</span><span class="k">new</span> <span class="nc">Props</span><span class="o">(</span><span class="nc">Swapper</span><span class="o">.</span><span class="n">class</span><span class="o">));</span>
    <span class="n">swap</span><span class="o">.</span><span class="n">tell</span><span class="o">(</span><span class="nc">SWAP</span><span class="o">);</span> <span class="c1">// logs Hi</span>
    <span class="n">swap</span><span class="o">.</span><span class="n">tell</span><span class="o">(</span><span class="nc">SWAP</span><span class="o">);</span> <span class="c1">// logs Ho</span>
    <span class="n">swap</span><span class="o">.</span><span class="n">tell</span><span class="o">(</span><span class="nc">SWAP</span><span class="o">);</span> <span class="c1">// logs Hi</span>
    <span class="n">swap</span><span class="o">.</span><span class="n">tell</span><span class="o">(</span><span class="nc">SWAP</span><span class="o">);</span> <span class="c1">// logs Ho</span>
    <span class="n">swap</span><span class="o">.</span><span class="n">tell</span><span class="o">(</span><span class="nc">SWAP</span><span class="o">);</span> <span class="c1">// logs Hi</span>
    <span class="n">swap</span><span class="o">.</span><span class="n">tell</span><span class="o">(</span><span class="nc">SWAP</span><span class="o">);</span> <span class="c1">// logs Ho</span>
  <span class="o">}</span>

<span class="o">}</span>
</pre></div>
</div>
</div>
<div class="section" id="downgrade">
<h3>Downgrade</h3>
<p>Since the hotswapped code is pushed to a Stack you can downgrade the code as
well. Use the <tt class="docutils literal"><span class="pre">getContext().unbecome</span></tt> method from within the Actor.</p>
<div class="highlight-java"><div class="highlight"><pre><span class="kd">public</span> <span class="kt">void</span> <span class="nf">onReceive</span><span class="o">(</span><span class="n">Object</span> <span class="n">message</span><span class="o">)</span> <span class="o">{</span>
  <span class="k">if</span> <span class="o">(</span><span class="n">message</span><span class="o">.</span><span class="na">equals</span><span class="o">(</span><span class="s">&quot;revert&quot;</span><span class="o">))</span> <span class="n">getContext</span><span class="o">().</span><span class="na">unbecome</span><span class="o">();</span>
<span class="o">}</span>
</pre></div>
</div>
</div>
</div>
<div class="section" id="killing-an-actor">
<h2>Killing an Actor</h2>
<p>You can kill an actor by sending a <tt class="docutils literal"><span class="pre">Kill</span></tt> message. This will restart the actor
through regular supervisor semantics.</p>
<p>Use it like this:</p>
<div class="highlight-scala"><div class="highlight"><pre><span class="k">import</span> <span class="nn">static</span> <span class="n">akka</span><span class="o">.</span><span class="n">actor</span><span class="o">.</span><span class="nc">Actors</span><span class="o">.*;</span>
    <span class="n">victim</span><span class="o">.</span><span class="n">tell</span><span class="o">(</span><span class="n">kill</span><span class="o">());</span>
</pre></div>
</div>
</div>
<div class="section" id="actors-and-exceptions">
<h2>Actors and exceptions</h2>
<p>It can happen that while a message is being processed by an actor, that some
kind of exception is thrown, e.g. a database exception.</p>
<div class="section" id="what-happens-to-the-message">
<h3>What happens to the Message</h3>
<p>If an exception is thrown while a message is being processed (so taken of his
mailbox and handed over the the receive), then this message will be lost. It is
important to understand that it is not put back on the mailbox. So if you want
to retry processing of a message, you need to deal with it yourself by catching
the exception and retry your flow. Make sure that you put a bound on the number
of retries since you don&#8217;t want a system to livelock (so consuming a lot of cpu
cycles without making progress).</p>
</div>
<div class="section" id="what-happens-to-the-mailbox">
<h3>What happens to the mailbox</h3>
<p>If an exception is thrown while a message is being processed, nothing happens to
the mailbox. If the actor is restarted, the same mailbox will be there. So all
messages on that mailbox, will be there as well.</p>
</div>
<div class="section" id="what-happens-to-the-actor">
<h3>What happens to the actor</h3>
<p>If an exception is thrown, the actor instance is discarded and a new instance is
created. This new instance will now be used in the actor references to this actor
(so this is done invisible to the developer). Note that this means that current
state of the failing actor instance is lost if you don&#8217;t store and restore it in
<tt class="docutils literal"><span class="pre">preRestart</span></tt> and <tt class="docutils literal"><span class="pre">postRestart</span></tt> callbacks.</p>
</div>
</div>
</div>


          </div>
          <div class="span3"><p class="contents-title">Contents</p>
              <div id="scroller-anchor">
                <div id="scroller">
                  <div id="toc"></div>
                </div>
              </div></div>
        </div>
      </div>
    </div>
  </div>
  <div class="footer">
  <div class="container">
    <ul>
      <li><h5>Akka</h5></li>
      <li><a href="http://akka.io/docs">Documentation</a></li>
      <li><a href="http://akka.io/downloads">Downloads</a></li>
    </ul>
    <ul>
      <li><h5>Contribute</h5></li>
      <li><a href="http://github.com/akka/akka">Source Code</a></li>
      <li><a href="http://groups.google.com/group/akka-user">Mailing List</a></li>      
      <li><a href="http://www.assembla.com/spaces/akka/tickets">Report a Bug</a></li>      
    </ul>
    <ul>
      <li><h5>Company</h5></li>
      <li><a href="http://typesafe.com/products/typesafe-subscription">Commercial Support</a></li>
      <li><a href="http://akka.io/team">Team</a></li>
      <li><a href="mailto:info@typesafe.com">Contact</a></li>
    </ul>
    <ul>
      <li><img src="../_static/watermark.png" align="center"/></li>
    </ul>
  </div>
  <div class="container copyright">
    <p style="float: left;">
      © 2012 <a href="http://typesafe.com/">Typesafe Inc.</a> <span class="license">Akka is Open Source and available under the Apache 2 License.</span>
    </p>
    <p style="float: right; font-size: 12px;">
      Last updated: Apr 13, 2012
    </p>          
  </div>
</div>
<script type="text/javascript">
  $('#toc').toc();
</script>
  

  </body>
</html>